container: Document that removal from foreach is permissible

It is permissable to remove a widget using gtk_container_remove from the
gtk_container_foreach callback handler. Document this fact to make it
more discoverable.

Fixes #1461

diff --git a/gtk/gtkcontainer.c b/gtk/gtkcontainer.c
index 7bb95246582700c603eb80ba926123097e1566c1..20f75f4ca79ec544e8cf35b78e37358e14cf4175 100644 (file)
--- a/gtk/gtkcontainer.c
+++ b/gtk/gtkcontainer.c
@@ -1574,6 +1574,8 @@ gtk_container_forall (GtkContainer *container,
  * added to the container by the application with explicit add()
  * calls.
  *
+ * It is permissible to remove the child from the @callback handler.
+ *
  * Most applications should use gtk_container_foreach(),
  * rather than gtk_container_forall().
  **/

diff --git a/gtk/gtkcontainer.h b/gtk/gtkcontainer.h
index 37d49805ccdb4aae6ece0253fa2c2189f8a77b73..8f07f974086b8ea4740a47a9801813342b8e4599 100644 (file)
--- a/gtk/gtkcontainer.h
+++ b/gtk/gtkcontainer.h
@@ -57,7 +57,8 @@ struct _GtkContainer
  * @add: Signal emitted when a widget is added to container.
  * @remove: Signal emitted when a widget is removed from container.
  * @check_resize: Signal emitted when a size recalculation is needed.
- * @forall: Invokes callback on each child of container.
+ * @forall: Invokes callback on each child of container. The callback handler
+ *    may remove the child.
  * @set_focus_child: Sets the focused child of container.
  * @child_type: Returns the type of the children supported by the container.
  * @set_child_property: Set a property on a child of container.